
/*
 * Copyright 2002-2019 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2019原作者。
 *
 *根据Apache许可证2.0版（“许可证”）许可；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，否则软件
 *根据许可证分发是在“按原样”的基础上分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证
 *许可证下的限制。
 */

package org.springframework.context;

/**
 * An extension of the {@link Lifecycle} interface for those objects that require
 * to be started upon {@code ApplicationContext} refresh and/or shutdown in a
 * particular order.
 *
 * <p>The {@link #isAutoStartup()} return value indicates whether this object should
 * be started at the time of a context refresh. The callback-accepting
 * {@link #stop(Runnable)} method is useful for objects that have an asynchronous
 * shutdown process. Any implementation of this interface <i>must</i> invoke the
 * callback's {@code run()} method upon shutdown completion to avoid unnecessary
 * delays in the overall {@code ApplicationContext} shutdown.
 *
 * <p>This interface extends {@link Phased}, and the {@link #getPhase()} method's
 * return value indicates the phase within which this {@code Lifecycle} component
 * should be started and stopped. The startup process begins with the <i>lowest</i>
 * phase value and ends with the <i>highest</i> phase value ({@code Integer.MIN_VALUE}
 * is the lowest possible, and {@code Integer.MAX_VALUE} is the highest possible).
 * The shutdown process will apply the reverse order. Any components with the
 * same value will be arbitrarily ordered within the same phase.
 *
 * <p>Example: if component B depends on component A having already started,
 * then component A should have a lower phase value than component B. During
 * the shutdown process, component B would be stopped before component A.
 *
 * <p>Any explicit "depends-on" relationship will take precedence over the phase
 * order such that the dependent bean always starts after its dependency and
 * always stops before its dependency.
 *
 * <p>Any {@code Lifecycle} components within the context that do not also
 * implement {@code SmartLifecycle} will be treated as if they have a phase
 * value of {@code 0}. This allows a {@code SmartLifecycle} component to start
 * before those {@code Lifecycle} components if the {@code SmartLifecycle}
 * component has a negative phase value, or the {@code SmartLifecycle} component
 * may start after those {@code Lifecycle} components if the {@code SmartLifecycle}
 * component has a positive phase value.
 *
 * <p>Note that, due to the auto-startup support in {@code SmartLifecycle}, a
 * {@code SmartLifecycle} bean instance will usually get initialized on startup
 * of the application context in any case. As a consequence, the bean definition
 * lazy-init flag has very limited actual effect on {@code SmartLifecycle} beans.
 *
 * @author Mark Fisher
 * @author Juergen Hoeller
 * @author Sam Brannen
 * @since 3.0
 * @see LifecycleProcessor
 * @see ConfigurableApplicationContext
 */
/**
 *｛@link Lifecycle｝接口的扩展，用于那些需要
 *在｛@code ApplicationContext｝刷新和/或关闭时启动
 *特定顺序。
 *
 *＜p＞｛@link#isAutoStartup（）｝返回值指示此对象是否应该
 *在上下文刷新时启动。接受回调
 *｛@link#stop（Runnable）｝方法对于具有异步
 *关闭过程。此接口<i>的任何实现都必须</i>调用
 *关闭完成时回调的｛@code run（）｝方法，以避免不必要的操作
 *｛@code ApplicationContext｝整体关闭的延迟。
 *
 *<p>此接口扩展了｛@link Phased｝，并且｛@link#getPhase（）｝方法的
 *返回值指示此｛@code Lifecycle｝组件所在的阶段
 *应该启动和停止。启动过程从<i>最低</i>开始
 *相位值，并以<i>最高</i>相位值结束（｛@code Integer.MIN_value｝
 *是尽可能低的，{@code Integer.MAX_VALUE}是尽可能高的）。
 *停机过程将采用相反的顺序。具有
 *相同的值将在相同的相位内被任意排序。
 *
 *＜p＞示例：如果组件B依赖于组件A已经启动，
 *则分量A应当具有比分量B更低的相位值
 *在停机过程中，部件B将在部件A之前停止。
 *
 *<p>任何明确的“依赖”关系都将优先于阶段
 *顺序，使得依赖bean总是在其依赖项之后启动，并且
 *总是在依赖项之前停止。
 *
 *<p>上下文中的任何｛@code Lifecycle｝组件
 *实现｛@code SmartLifecycle｝将被视为有一个阶段
 *｛@code 0｝的值。这允许｛@code SmartLifecycle｝组件启动
 *如果｛@code SmartLifecycle｝
 *组件具有负相位值，或者｛@code SmartLifecycle｝组件
 *如果｛@code SmartLifecycle｝
 *组件具有正相位值。
 *
 *<p>请注意，由于｛@code SmartLifecycle｝中的自动启动支持
 *｛@code SmartLifecycle｝bean实例通常会在启动时初始化
 *在任何情况下都是应用程序上下文的一部分。因此，bean定义
 *惰性初始化标志对{@code SmartLifecycle}bean的实际影响非常有限。
 *
 *@作者Mark Fisher
 *@作者Juergen Hoeller
 *@作者Sam Brannen
 *@自3.0起
 *@请参阅生命周期处理器
 *@请参阅可配置的应用程序上下文
 */
public interface SmartLifecycle extends Lifecycle, Phased {

	/**
	 * The default phase for {@code SmartLifecycle}: {@code Integer.MAX_VALUE}.
	 * <p>This is different from the common phase {@code 0} associated with regular
	 * {@link Lifecycle} implementations, putting the typically auto-started
	 * {@code SmartLifecycle} beans into a later startup phase and an earlier
	 * shutdown phase.
	 * @since 5.1
	 * @see #getPhase()
	 * @see org.springframework.context.support.DefaultLifecycleProcessor#getPhase(Lifecycle)
	 */
	/**
	 *｛@code SmartLifecycle｝的默认阶段：｛@codeInteger.MAX_VALUE｝。
	 *＜p＞这不同于与正则表达式关联的公共阶段｛@code 0｝
	 *｛@link Lifecycle｝实施，将通常自动启动的
	 *｛@code SmartLifecycle｝bean进入后期启动阶段和早期启动阶段
	 *停机阶段。
	 *@自5.1起
	 *@参见#getPhase（）
	 *请参阅org.springframework.context.support.DefaultLifecycleProcessor#getPhase（生命周期）
	 */
	int DEFAULT_PHASE = Integer.MAX_VALUE;


	/**
	 * Returns {@code true} if this {@code Lifecycle} component should get
	 * started automatically by the container at the time that the containing
	 * {@link ApplicationContext} gets refreshed.
	 * <p>A value of {@code false} indicates that the component is intended to
	 * be started through an explicit {@link #start()} call instead, analogous
	 * to a plain {@link Lifecycle} implementation.
	 * <p>The default implementation returns {@code true}.
	 * @see #start()
	 * @see #getPhase()
	 * @see LifecycleProcessor#onRefresh()
	 * @see ConfigurableApplicationContext#refresh()
	 */
	/**
	 *如果此｛@code Lifecycle｝组件应该
	 *容器在包含时自动启动
	 *｛@link ApplicationContext｝被刷新。
	 *＜p＞｛@code false｝的值表示该组件旨在
	 *而是通过显式｛@link#start（）｝调用启动，类似于
	 *到一个简单的｛@link Lifecycle｝实现。
	 *＜p＞默认实现返回｛@code true｝。
	 *@参见#start（）
	 *@参见#getPhase（）
	 *@see生命周期处理器#onRefresh（）
	 *@请参阅ConfigurationApplicationContext#refresh（）
	 */
	default boolean isAutoStartup() {
		return true;
	}

	/**
	 * Indicates that a Lifecycle component must stop if it is currently running.
	 * <p>The provided callback is used by the {@link LifecycleProcessor} to support
	 * an ordered, and potentially concurrent, shutdown of all components having a
	 * common shutdown order value. The callback <b>must</b> be executed after
	 * the {@code SmartLifecycle} component does indeed stop.
	 * <p>The {@link LifecycleProcessor} will call <i>only</i> this variant of the
	 * {@code stop} method; i.e. {@link Lifecycle#stop()} will not be called for
	 * {@code SmartLifecycle} implementations unless explicitly delegated to within
	 * the implementation of this method.
	 * <p>The default implementation delegates to {@link #stop()} and immediately
	 * triggers the given callback in the calling thread. Note that there is no
	 * synchronization between the two, so custom implementations may at least
	 * want to put the same steps within their common lifecycle monitor (if any).
	 * @see #stop()
	 * @see #getPhase()
	 */
	/**
	 *指示如果生命周期组件当前正在运行，则必须停止该组件。
	 *＜p＞提供的回调由｛@link LifecycleProcessor｝用于支持
	 *所有具有
	 *通用停机指令值。回调＜b＞必须在
	 *｛@code SmartLifecycle｝组件确实停止了。
	 *＜p＞｛@link LifecycleProcessor｝将只调用＜i＞这个
	 *｛@code stop｝方法；即不会调用{@link Lifecycle#stop（）}
	 *｛@code SmartLifecycle｝实施，除非明确委托给
	 *这个方法的实现。
	 *＜p＞默认实现委托给｛@link#stop（）｝并立即
	 *在调用线程中触发给定的回调。请注意，没有
	 *两者之间的同步，因此自定义实现至少可以
	 *希望将相同的步骤放在他们的通用生命周期监控器中（如果有的话）。
	 *@见#stop（）
	 *@参见#getPhase（）
	 */
	default void stop(Runnable callback) {
		stop();
		callback.run();
	}

	/**
	 * Return the phase that this lifecycle object is supposed to run in.
	 * <p>The default implementation returns {@link #DEFAULT_PHASE} in order to
	 * let {@code stop()} callbacks execute after regular {@code Lifecycle}
	 * implementations.
	 * @see #isAutoStartup()
	 * @see #start()
	 * @see #stop(Runnable)
	 * @see org.springframework.context.support.DefaultLifecycleProcessor#getPhase(Lifecycle)
	 */
	/**
	 *返回此生命周期对象应该在其中运行的阶段。
	 *＜p＞默认实现返回｛@link#default_PHASE｝以便
	 *让{@code stop（）}回调在常规{@code生命周期}之后执行
	 *实现。
	 *@参见#isAutoStartup（）
	 *@参见#start（）
	 *@见#stop（可跑步）
	 *请参阅org.springframework.context.support.DefaultLifecycleProcessor#getPhase（生命周期）
	 */
	@Override
	default int getPhase() {
		return DEFAULT_PHASE;
	}

}
